feat(spec): TryCatchErrorValueSchema declares the optional open-string code key the try_catch engine binds - #15672

Fixes #14954

What

packages/spec/src/automation/control-flow.zod.ts — TryCatchErrorValueSchema gains an optional code: z.string() key, and the try_catch config's errorVariable describe names it, so the ONE shape the catch region's author, the engine and the run log share again equals what the engine binds. PR #14948 (#14419) added that fifth key on the engine side; the schema was a plain z.object that did not declare it, so any round-trip through the declared shape silently STRIPPED it, and the generated reference page documented four keys where the runtime binds five.

Typed as an OPEN string, deliberately not StandardErrorCode and not the ledger union. The card's warning, quoted from its body: "string, not a closed enum — and this is the part worth not getting wrong. ADR-0112 D3/D4 (with the #9106 amendment) makes the code vocabulary StandardErrorCode ∪ registered ledger codes ∪ tenant-authored codes, and NodeExecutor is third-party-registrable, so a closed type would be a lie the moment anyone registers an executor." The closed-at-every-door rule governs ApiErrorSchema.code at an HTTP door; this value is bound in-process and never crosses one. The docblock on the schema says the same, so the next author is told which decision they are standing on.

The describe text, verbatim

code (on TryCatchErrorValue):

Platform-classified error code (ADR-0112) of the failure that ended the try region, e.g. create_record's DUPLICATE_RECORD; present only when the failing node's own result carried one, so a catch region branching on $error.code treats "unset" as "no classified code", never as "nothing failed". An open string, not a closed enum: the vocabulary is StandardErrorCode plus registered ledger codes plus tenant-authored codes, and third-party node executors bind their own

errorVariable (on TryCatchConfig):

Variable holding the caught error in the catch region — a TryCatchErrorValue: nodeId, message, code when the failing node carried a platform-classified error code (ADR-0112 — branch on $error.code to tell "the row is already there" from "the store is down"), and iteration / item when the failure happened inside a loop body

Generated followers — regenerated, never hand-edited

Derived, not guessed: pnpm --filter @objectstack/spec build (runs gen:schema), then pnpm --filter @objectstack/spec check:generated to name what is stale, then check:generated --fix, which regenerates only what the sweep proved stale.

• packages/spec/authorable-surface/automation.json — rewritten by gen:schema during the build: +1 entry, automation/TryCatchErrorValue:code.
• content/docs/references/automation/control-flow.mdx — the ONE artifact check:generated named stale (✗ check:docs, "1 of 15 artifact(s) stale"); regenerated by gen:docs through --fix: the errorVariable row changes and a code row joins the TryCatchErrorValue table.
• Measured unchanged by the same sweep (each ✓): api-surface/ (no new export — TryCatchErrorValue (type) / TryCatchErrorValueSchema (const) were already listed), json-schema.manifest/ (the schema set is unchanged), export-origins/, declaration-map/, spec-changes.json, docs/protocol-upgrade-guide.md, authorable-surface.base.json (the anchor: it lags by design, was not hand-adjusted, and check:authorable-surface is green).

Strictness-ledger reading

check:strictness-ledger tracks per-file strip-site COUNTS and each row's Class verdict, not a schema's key set. control-flow.zod.ts keeps exactly one strip site — TryCatchErrorValueSchema, class wire, the "+1 at #13681" row — and an additive optional key moves neither the count nor the class, so the generated counts artifact is unchanged and the gate is green (check:generated prints ✓ check:strictness-ledger; the standalone run exits 0). The hand-written row's key list records what #13681 added and stays true as history; not edited. ADR-0087: an additive optional key retires nothing, so no entry is owed; node scripts/check-adr-0087-registration.mjs --base origin/main exits 0 on this changeset (that gate judges declared-breaking changesets only).

Changeset

.changeset/try-catch-error-value-code-key.md — @objectstack/spec: minor. Semver derivation in one line: a new optional key on a published schema widens the accept set and the exported TryCatchErrorValue type without retiring or renaming anything ⇒ minor (not patch — it is a contract widening rather than a behaviour repair; not major — nothing that parsed before stops parsing).

Verification — every reading below is on 214ae5211, this PR's head (git rev-parse --short HEAD = 214ae5211)

Heavy runs went through scripts/pm/os-verify-lock.sh; verdict lines are quoted from the tools' own output, exit codes captured before any pipe.

• Spec unit tests — pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/automation/control-flow.test.ts → Test Files 1 passed (1) · Tests 45 passed (45) (lock VERDICT command-exit 0). Four new pins: a round-trip preserves code (asserted as whole-object equality, since a plain z.object strips silently); code is optional and the key is ABSENT, not undefined, when no classified code was carried, and composes with iteration / item; the value is an OPEN string — ACME_RATE_LIMITED and DUPLICATE parse, while code: 42 is refused at path ['code'] with invalid_type; the describe text reaches the JSON schema (z.toJSONSchema) on both the value and errorVariable.
• pnpm --filter @objectstack/spec typecheck → exit 0 (tsc --noEmit, check:scripts-typecheck, check:test-typecheck: OK); tsc -p tsconfig.test.json --listFilesOnly reaches src/automation/control-flow.test.ts (1 hit), so the test layer's verdict covers the edited test file.
• Consumer package, downstream direction (the package that binds the value): dependency closure built first — pnpm turbo run build --filter="@objectstack/service-automation^..." → Tasks: 20 successful, 20 total — then pnpm --filter @objectstack/service-automation exec vitest run --maxWorkers=2 → Test Files 107 passed (107) · Tests 1290 passed (1290) (lock VERDICT command-exit 0). That package's vitest config aliases only @objectstack/platform-objects to src; @objectstack/spec resolves through the workspace link to the REBUILT dist, so the automation: create_record collapses the engine's DUPLICATE_RECORD envelope to a string, so a flow's try_catch / fault edge still cannot tell "already there" from "the store is down" #14419 pins in create-record-duplicate-code.test.ts (expect(seen[0]?.code).toBe('DUPLICATE_RECORD'), the loop-row case and the stale-code cases) ran against the new declaration. pnpm --filter @objectstack/service-automation typecheck → exit 0.
• Reverse verification, so the consumer readings are of the rebuilt .d.ts and not a cache: a scratch file under packages/services/service-automation/src assigning { nodeId, message, code: 42 } to TryCatchErrorValue → error TS2322: Type 'number' is not assignable to type 'string' (exit 2, exactly one error), while the positive control on the next line, code: 'DUPLICATE_RECORD', compiled. packages/spec/dist/automation/index.d.ts:1247 reads code: z.ZodOptional wrapping z.ZodString. The scratch file was deleted; git status is clean.
• Gate families — derived off the ACTUAL diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths; it reported "5 path(s) vs merge base 7087f99 of 'origin/main' and HEAD"): 93 commands, each run on its own with the exit captured before any pipe. 91 exit 0, including every family the dispatch named (check:api-surface, check:authorable-surface, check:browser-reachable-entries, check:dual-source-exports, check:entry-nameability, check:export-origins, check:docs, check:empty-state, check:changeset-gate-self-tests, check:corpus-claim-drift, check:cross-package-test-inputs, check:doc-anchors, check:doc-authoring, check:docs-audit-scope, check:docs-redirects, check:docs-single-h1, check:doc-formula-expressions, check:doc-security-posture) plus, among those the derivation added, check:nul-bytes, check:strictness-ledger, check:generated, check:merge-driver, check:test-source-alias, the changeset trio (check-empty-changeset, check-changeset-no-major, check-adr-0087-registration) and check:skill-examples (✅ 257 prose examples type-check across 3 surface(s), after building @objectstack/client and @objectstack/client-react so its SDK surface could measure). Two are NOT MEASURED locally, by their own verdict text, and belong to CI: check:dual-build-cjs-loads (exit 3, PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/, 49 unbuilt packages) and check:type-check-debt (exit 3, Build the closure first … This is NOT a pass and NOT a finding). One transient, stated rather than hidden: check:docs-audit-scope went red once (affected-docs self-test, 1 of 568 cases) while an aborted first check:skill-examples run had left its extracted-example build files in the tree; it is green on a pristine 7087f99c compare worktree and green on re-run after the clean check:skill-examples pass, with 0 ignored .ts files remaining under packages/.
• pnpm lint (repo-wide eslint) was not run locally and no narrowing measurement is claimed for it — CI owns that run.

Hand-written docs

content/docs/automation/flows.mdx:1133 already documents {$error.code} (from PR #14948) in terms consistent with the describe text above — "absent otherwise, so a handler branching on it should treat "unset" as "no classified code", not as "nothing failed"" — so nothing there is false; not edited.

Out of scope, filed

• [finding] service-automation: the local TryCatchErrorValue & { code?: string } widening in try-catch-node.ts becomes redundant once packages/spec declares code (#14954 follow-up) #15669 — the engine's local TryCatchErrorValue & { code?: string } widening at try-catch-node.ts:235 becomes redundant once this lands; a domain:services file, so it is a follow-up with Blocked-by: #14954 rather than a rider here.

🤖 Generated with Claude Code

Generated by Claude Code